home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / edit / me_cd25.zip / DOC.ZIP / ME2MUTT.DOC < prev    next >
Text File  |  1992-11-09  |  59KB  |  1,190 lines
  1. !!!Concepts chapter:
  2.   talk about garbage collection:  what when
  3.   talk general about bags, marks, buffers
  4.   talk about current buffer, current window ain't the same
  5. ========================================================================
  6. ==    The ME Mutt Connection        Craig Durland  9/89 10/91 11/91   ==
  7. ========================================================================
  8.  
  9.   This document describes the link between the Mutt2 programming
  10. language (see MUTT2.DOC) and the Mutt Editor II (see ME2.DOC).
  11.  
  12.  
  13.              Copyright 1991 Craig Durland
  14.     Distributed under the terms of the GNU General Public License.
  15.   Distributed "as is", without warranties of any kind, but comments,
  16.            suggestions and bug reports are welcome.
  17.  
  18. ========================================================================
  19. ==        The ME2 Mutt functions                      ==
  20. ========================================================================
  21. (append-to-bag bag-id TEXT      <text>)
  22. (append-to-bag bag-id REGION      [mark1 mark2])
  23. (append-to-bag bag-id CHARACTERS <number>)
  24. (append-to-bag bag-id RECTANGLE  [mark1 mark2])
  25.       where TEXT = 0, CHARACTERS = 1, REGION = 2 and RECTANGLE = 3.
  26.  
  27.     TEXT       :    [NUMBER 0 STRING         : VOID]
  28.     REGION       :    [NUMBER 1 [NUMBER [NUMBER]] : VOID]
  29.     CHARACTERS :    [NUMBER 2 NUMBER        : VOID]
  30.     RECTANGLE  :    [NUMBER 3 [NUMBER [NUMBER]] : VOID]
  31.  
  32.   These functions append text to a bag.  
  33.     TEXT : Appends a string to the bag.
  34.     REGION : Appends the text contained in a region.
  35.     CHARACTERS : Appends n characters, starting from the dot.
  36.     RECTANGLE :    Copies the region-rectangle.  This clears the bag first.
  37.       Note that appending anything to a bag with a rectangle in it
  38.       (unless it is another rectangle) is a no-op until you clear the
  39.       bag.
  40.  
  41.   For example:
  42.     If the region contains "This is a test" then
  43.       (clear-bag 0)
  44.       (append-to-bag 0 REGION) (append-to-bag 0 TEXT " foo bar")
  45.     will set the cut buffer to "This is a test foo bar".
  46.   See also:  create-bag, clear-bag, insert-register, bag-stats,
  47.     bag-to-string.
  48. (arg-flag)                           [zip : BOOLEAN]
  49.   Check to see if somebody set the arg-prefix before calling this
  50.     routine (via (universal-argument) or (arg-prefix n)).
  51.   See also: arg-prefix.
  52. (arg-prefix [arg])                       [[NUMBER] : NUMBER]
  53.   Get or set the universal-argument.
  54.   With an arg, its the same as ^U before a function.
  55.     Notes:
  56.       The arg-flag is set to TRUE.
  57.       This really sets two prefixes:  one for ME commands and one for
  58.     Mutt programs.  ME commands and exe-key use and reset the prefix
  59.     to 1.  Programs can only read the prefix and so it will stay the
  60.     same for all children of a program unless it is changed by
  61.     (arg-prefix n).  If it is changed, all the children AND parents
  62.     will see the new value.  It is a good idea to make a copy of the
  63.     value upon entry to a program if it is possible that a child
  64.     might change it.
  65.       If prefix is not set, it is always 1 (and the arg-flag is FALSE)
  66.     when a program or ME command is run from the keyboard.
  67.   Note that there is a difference between (arg-prefix 1) and the default.
  68.     Setting arg-prefix sets arg-flag.  There are commands that just look
  69.     at arg-flag and do different things if it is set.
  70.   For example, to make META-n start the (universal-argument) count at n,
  71.     use the following (where n is 1,2,3,4,5,6,7,8 or 9):
  72.     (defun
  73.       META-arg { (arg-prefix (- (key-pressed) 0x230))(universal-argument) }
  74.       MAIN
  75.       {
  76.     (int j)
  77.     (for (j 1)(< j 10)(+= j 1)
  78.       (bind-to-key (concat "META-arg")(concat "M-" j)))
  79.       }
  80.     )
  81.   See also: (arg-flag), (universal-argument) in ME2.DOC.
  82. (argc)                                [zip : NUMBER]
  83.   The number of parameters on the command line when ME was invoked +1.
  84.   eg "ME2 foo bar" has argc == 3.
  85.   Use argv to look at the parameters.
  86. (argv)                             [NUMBER : STRING]
  87.   The ME command line parameters.  There are argc of them, numbering
  88.     0...argc-1.  (argv 0) is the name of the program (ME) (unless you are
  89.     running on MS-DOS 2.x where it is ""), (argv 1) is the first file name
  90.     (which is loaded by me2.mut), (argv 2) is the next file name, etc.
  91.   See nextfile.mut for an example.
  92. (attached-buffer window-id | buffer-name)      [NUMBER|STRING : NUMBER]
  93.   If given a number, attached-buffer returns the buffer id that is
  94.     attached to window n.  n == -1 means use the current window.
  95.   If given a name, attached-buffer returns the id of the buffer that is
  96.     named name.  Returns -2 if the buffer does not exist.
  97.   For example:
  98.     if the cursor is in third window (window #2) which is displaying
  99.       buffer "foobar" and foobar has an id of 123 then:
  100.     (attached-buffer -1) and (attached-buffer 2) both return 123.
  101.     (attached-buffer "foobar") returns 123.
  102.     (attached-buffer "FOOBAR") returns -2.
  103.   See also: buffers, windows.
  104.  
  105. (bag-stats bag-id pointer-to-data)             [NUMBER BLOB : VOID] 
  106.   Get stats on a bag.  pointer-to-data is a pointer the the data area
  107.     that the stats are put into:
  108.   (byte type) (small-int width height) (int size)    ;; struct BagInfo
  109.     type: 0 means text and 1 is rectangle.
  110.     width, height:  If the register is a rectangle.
  111.     size: Number of bytes in the register.
  112.   For example:
  113.     (defun get-bag-stats
  114.     {
  115.       (byte type)(small-int width height)(int size)    ;; struct BagInfo
  116.       (int n)
  117.  
  118.       (n (convert-to 3 (ask "bag id: ")))
  119.       (bag-stats n (loc type))
  120.       (msg "bag[" n "]: " (if (== type 0) "Text." "Rectangle.")
  121.     " Width:" width " Height:" height " Size:" size
  122.       )
  123.     })
  124.   Note:
  125.     If the bag is not a rectangle, the width and height are garbage.
  126.   See also:  append-to-bag, clear-bag, insert-bag.
  127. (bag-to-file bag-id file-name)             [NUMBER STRING : BOOLEAN]
  128.   Copy the contents of a bag to a file.  If the file already exists, it
  129.     is overwritten.
  130.   If bag-id is bad, the program aborts.
  131.   If some kind of error occurs (can't open file-name or can't write all
  132.     of bag), FALSE is returned so you can clean up if necessary.
  133.   See also: file-to-bag, bag-to-string
  134. (bag-to-string bag-id)                     [NUMBER : STRING]
  135.   Convert bag contents to a string.
  136.   If the bag contains a rectangle, the string will be each line of the
  137.     rectangle, one after the other.
  138.   Note:
  139.     The string sticks around until the bag is changed (clear-bag,
  140.     append-to-bag, etc).  At that point, the string is garbage and can
  141.     cause unknown behavior if used.  Use the string or save it - don't
  142.     expect it to hang around.
  143.   See also: append-to-bag
  144. (bit-and x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  145.   Binary and 2 or more numbers.
  146.   See also bit-or, bit-xor.
  147. (bit-or  x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  148.   Binary or 2 or more numbers.
  149.   See also bit-and, bit-xor.
  150. (bit-xor x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  151.   Binary xor 2 or more numbers.
  152.   See also bit-and, bit-or.
  153. (buffer-flags buffer-id [flags])        [NUMBER [NUMBER] : NUMBER]
  154.   Get or set the buffer flags.  There are 32 flags.
  155.     Bit        Flag    Notes
  156.     ---        ----    -----
  157.     0x0001  Modified    1 if the buffer has been modified since last save.
  158.     0x0002  NoCare    1 if don't care about buffer contents.
  159.     0x0004  Hidden    1 if buffer is hidden from user.
  160.     0x0008  Undo    1 if undo is turned on for the buffer.
  161.     0x0010  Mode    Tickle bit: force (modeline-hook) to be called.
  162.     0x0020  Immortal    Not a temporary buffer.
  163.     0x0040  Interactive A buffer for humans.
  164.  
  165.     The lower eight bits are reserved for ME2's use, you can use the
  166.       other 24.  Note - you might want to leave a few bits at the bottom
  167.       unused in case I need some more in the future.
  168.   Notes:
  169.     The Modified flag is set whenever the buffer changes.  When it
  170.       changes, (modeline-hook) is called.
  171.     The NoCare flag is used whenever ME wants exit or change a buffer -
  172.       it is set, ME will not ask before changes are made.
  173.     A buffer with the Hidden flag set is invisible to the user -
  174.       (next-buffer) skips it, the help and command completion routines
  175.       ignore it.
  176.     If you want a buffer to have u